Introduction

This document details the Atlas of Living Australia style guide for creating html files from R Markdown

Style Template

A test of a chunk

library(kableExtra)
library(tidyverse)

# a table
head(mtcars, n=5) %>%
  kbl() %>%
  kable_styling()
mpg cyl disp hp drat wt qsec vs am gear carb
Mazda RX4 21.0 6 160 110 3.90 2.620 16.46 0 1 4 4
Mazda RX4 Wag 21.0 6 160 110 3.90 2.875 17.02 0 1 4 4
Datsun 710 22.8 4 108 93 3.85 2.320 18.61 1 1 4 1
Hornet 4 Drive 21.4 6 258 110 3.08 3.215 19.44 1 0 3 1
Hornet Sportabout 18.7 8 360 175 3.15 3.440 17.02 0 0 3 2



Getting started

Use ALA Template

Create a new R Markdown document by selecting File –> New File –> R Markdown

In the left window menu, select New Template. Then select the ALA Template

Add your information

  1. In the top 3 lines, add your document title, your name and the date. Leave the remainder of the .yaml options unchanged.

  2. Next, scroll down to the code chunk named upper right bio. This code chunk adds your image and links to your personal websites

    • Save your preferred picture as “picture.jpg” in the current directory
    • Add the urls you wish to link to for the correct websites & icons
`{r upper right bio, echo = FALSE}
htmltools::withTags(
  div(id = "pictureposition",
      
      
# Save your own picture as "picture.jpg" to local directory
      img(src = knitr::image_uri("picture.jpg"),
          class = "clipped", 
          style = 'height:100px'),
      
# Add links to personal accounts below and uncomment
      div(id = "linkposition",
          # a(href="your-url",              # twitter
          #   class="fab fa-twitter",
          #   style = "text-align:center"),
          # a(href="your-url",              # github
          #   class="fab fa-github",
          #   style = "text-align:center")
          # a(href="your-url",              # linkedIn
          #   class="fab fa-linkedin",
          #   style = "text-align:center")
          )))
`


Knit to HTML

Click the Knit button in the upper menu (below file tabs, above script) to create an HTML file. A preview of your knitted HTML document can be viewed in the right pane. Code must run successfully from start to finish for a file to be Knit.

In the R Studio viewer pane, click the “Show in New Window ” button to view the page in your browser.



Push to Github



Reproducible workflows

Safe paths

Using setwd() to set a working directory can create issues for folder paths. They often are a cause of issues when making reproducible workflows.

Instead, use the here() function from the here package to build the path where you read and write files. here() automatically creates paths relative to the top level directory.

Read a full description of how to use the here() function to create safe paths in Chapter 3 of What They Forgot to Teach You About R

For example:

library(ggplot2)
library(here)

df <- read.delim(here("projects", , "style_guide", "data.csv"))
p <- ggplot(df, aes(x, y)) + geom_point()
ggsave(here("plots", "foofy_scatterplot.png"))

To set the project root path according to your current code file:

here::i_am("style_guide.rmd")

Make understandable code

Code chunk size

In writing, we use sentences and paragraphs of varying lengths to build a flowing, logical story or argument. In the same way, code chunks can be used to structure lines of code to build a flowing, logical analysis or plot.

Code chunks should be brief. They should also offer notes or visual output that provides context to any transformations or outputs. Users should be able to follow each transformation that is made to your data, each output that results from a transformation, and any final output.

There is no single correct code chunk size - you must use your best judgement. If it seems that the result of one or several lines of code is unclear a potential reader, you may need to split the code chunks to make the results easier to follow.

Brief summaries

For others to understand what your code does and why you made the choices you did, it is helpful to include brief summaries or your logic or what each line of your code does. It is also good to provide a brief interpretation of model output

Style code using styler

Use the styler package to ensure your code is formatted correctly and/or consistently, The styler package formats your code according to the tidyverse style guide (or another custome style) prior to uploading a finished file document.

See the styler github and tidyverse pages for more information

Install the styler package to add style buttons to your R Markdown Addins dropdown menu. Clicking Addins -> style active file will reformat the code in your active file. Clicking ** Addins** -> style active section will reformat code in your current section.

Alternatively, you style_file() or style_text() can be run in the console.

Output style

See the R Markdown cheat sheet for more information on R Markdown formatting

For tips to make your R Markdown output pretty, see Pimp my RMD by Yan Holtz

Tables

Several packages can create tables with nice formatting.

One example is kableExtra:

library(kableExtra)
kable(
  head(mtcars, n=5)) %>% kable_styling()
mpg cyl disp hp drat wt qsec vs am gear carb
Mazda RX4 21.0 6 160 110 3.90 2.620 16.46 0 1 4 4
Mazda RX4 Wag 21.0 6 160 110 3.90 2.875 17.02 0 1 4 4
Datsun 710 22.8 4 108 93 3.85 2.320 18.61 1 1 4 1
Hornet 4 Drive 21.4 6 258 110 3.08 3.215 19.44 1 0 3 1
Hornet Sportabout 18.7 8 360 175 3.15 3.440 17.02 0 0 3 2


kableExtra is also able to be used using magittr or base piping:

mtcars %>% 
  group_by(gear) %>% 
  summarise(cyl = mean(cyl),
            disp = mean(disp)) %>%
  kbl() %>%
  kable_styling()
gear cyl disp
3 7.466667 326.3000
4 4.666667 123.0167
5 6.000000 202.4800
head(mtcars |>
  subset(select = c("cyl", "disp", "gear")), n = 5) |>
  kbl() |>
  kable_styling()

Figures

Controlling the size of figures can help when you want people to focus on trends of many plots or on details of a single plot.

You can control how many columns your plots created in a chunk are printed into.
Add out.width = c("50%", "50%"), fig.show = "hold":

``{r out.width=c('50%', '50%'), fig.show='hold'}
boxplot(1:10)
plot(rnorm(10))
`

Control other parts of figure output in the chunk header as well. For example:

``{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure: Here is a really important caption."}
library(tidyverse)
mpg %>%
  ggplot( aes(x=reorder(class, hwy), y=hwy, fill=class)) + 
    geom_boxplot() +
    xlab("class") +
    theme(legend.position="none")
Figure: Here is a really important caption.

Figure: Here is a really important caption.

Model output

Run a model and want to show output? Use the model_parameters() function from the parameters package to make your output clear and organised. The model_parameters() function can be considered as a lightweight alternative to broom::tidy():

library(parameters)
model <- lm(Sepal.Width ~ Petal.Length * Species + Petal.Width, data = iris)

# regular model parameters
model_parameters(model)
## Parameter                           | Coefficient |   SE |         95% CI | t(143) |      p
## -------------------------------------------------------------------------------------------
## (Intercept)                         |        2.89 | 0.36 | [ 2.18,  3.60] |   8.01 | < .001
## Petal.Length                        |        0.26 | 0.25 | [-0.22,  0.75] |   1.07 | 0.287 
## Species [versicolor]                |       -1.66 | 0.53 | [-2.71, -0.62] |  -3.14 | 0.002 
## Species [virginica]                 |       -1.92 | 0.59 | [-3.08, -0.76] |  -3.28 | 0.001 
## Petal.Width                         |        0.62 | 0.14 | [ 0.34,  0.89] |   4.41 | < .001
## Petal.Length * Species [versicolor] |       -0.09 | 0.26 | [-0.61,  0.42] |  -0.36 | 0.721 
## Petal.Length * Species [virginica]  |       -0.13 | 0.26 | [-0.64,  0.38] |  -0.50 | 0.618

model_parameters() can also be used for parameter standardization:

# standardized parameters
model_parameters(model, standardize = "refit")
## Package 'effectsize' required to calculate standardized coefficients. Please install it.
## Parameter                           | Coefficient |   SE |         95% CI | t(143) |      p
## -------------------------------------------------------------------------------------------
## (Intercept)                         |        2.89 | 0.36 | [ 2.18,  3.60] |   8.01 | < .001
## Petal.Length                        |        0.26 | 0.25 | [-0.22,  0.75] |   1.07 | 0.287 
## Species [versicolor]                |       -1.66 | 0.53 | [-2.71, -0.62] |  -3.14 | 0.002 
## Species [virginica]                 |       -1.92 | 0.59 | [-3.08, -0.76] |  -3.28 | 0.001 
## Petal.Width                         |        0.62 | 0.14 | [ 0.34,  0.89] |   4.41 | < .001
## Petal.Length * Species [versicolor] |       -0.09 | 0.26 | [-0.61,  0.42] |  -0.36 | 0.721 
## Petal.Length * Species [virginica]  |       -0.13 | 0.26 | [-0.64,  0.38] |  -0.50 | 0.618


Code chunk options

See the R markdown documentation to view chunk options.

Example: echo and eval

Readers should be able to identify where every file in a workflow comes from (little is more frustrating than wondering where a required data file is located). Code used to load or extract data (from galah, for example) should be clearly identified.

However, some code takes a very long time to run and you may have saved it locally or in a repository to save time and/or space. In this case, it is possible to show code without running it.

Add eval = FALSE to the chunk header to display the code but prevent the chunk from running:

``{r, eval = FALSE}
ala_counts(group_by = "phylum")
`

You can then load a local file in the background, without showing the code.

Add echo = FALSE to your chunk header to run the code but prevent the chunk from displaying:

``{r, echo = FALSE}
data <- readRDS(file = "local_file.rds")
`